Modefull vs. Modeless
Opening a modefull dialog preempts any input in another window of the application until the dialog is closed again. Modefull dialog windows are used, for example, by the class Alert and the class FileDialog. Modeless dialogs, however, do not block other windows. An example for that is the "Find/Change" dialog (see class ChangeDialog).
Whether a dialog is modefull or modeless is specified in the windowFlags argument of the constructor of Dialog. If the flag eBWinBlock is set, then the dialog is modefull, otherwise it is modeless (see also enum BWinFlags).
Opening a Dialog
Dialogs are opened either with the method Show or the method ShowOnWindow. The first one opens the window at the position where the last mouse event occurred whereas the latter positions the window at the center of a VObject. Before the dialog is opened the actual position is additionally modified by the method GetInitialPos. The default implementation returns the center of the default ActionButton which means that after opening the dialog that button is always exactly located under the mouse cursor.
If the dialog is modefull, then Show and ShowOnWindow block until the dialog is accepted or cancelled and then return the id of the selected ActionButton.
In case of a modeless dialog Show and ShowOnWindow immediately return after opening the dialog window without waiting for events. This means that the returned id cannot be used. The method Control has to be overridden and events from dialog items must be processed there.
Dialog Setup
The purpose of the method DoSetDefaults is to initialize the dialog items with some reasonable default values. The method DoSetup has to enable/disable the dialog items and initialize their values according to the data shown in the dialog. DoSetup is called whenever the dialog is opened whereas DoSetDefaults is called only when the dialog is opened the first time. Both methods are also invoked if a dialog item with the id const cIdDefault is selected.
Validation, Acceptation, Cancellation
If an ActionButton, whose id is different from const cIdCancel, is selected, then the dialog is validated. Validation means that all dialog items check whether the data entered by the user can be accepted; e.g. the class NumItem tests whether the entered number is in a certain range. If validation fails an error is reported and the dialog window stays open.
A dialog is accepted when the Ok button (an ActionButton with the id const cIdOk) is selected and validation is successful. The data entered by the user is then stored by the method DoStore and the dialog window is closed.
Cancellation is triggered by the Cancel button (an ActionButton with the id const cIdCancel). The data entered by the user is discarded. The original data, which has been saved by the method DoSave before opening the dialog window, is restored through the method DoRestore and the dialog window is closed.
Validation, acceptation and cancellation is performed by the method Control.
classes are always derived from Dialog.
class Dialog
is never reused directly.
class Dialog is abstract.
class Dialog contains 15 methods.
Dialogs
man2html: unable to open or read file ../mann/Dialog::Close.n
man2html: unable to open or read file ../mann/Dialog::Control.n
man2html: unable to open or read file ../mann/Dialog::Dialog.n
man2html: unable to open or read file ../mann/Dialog::DoRestore.n
man2html: unable to open or read file ../mann/Dialog::DoSave.n
man2html: unable to open or read file ../mann/Dialog::DoSetDefaults.n
man2html: unable to open or read file ../mann/Dialog::DoSetup.n
man2html: unable to open or read file ../mann/Dialog::DoStore.n
man2html: unable to open or read file ../mann/Dialog::GetInitialPos.n
man2html: unable to open or read file ../mann/Dialog::InspectorId.n
man2html: unable to open or read file ../mann/Dialog::SetTitle.n
man2html: unable to open or read file ../mann/Dialog::Show.n
man2html: unable to open or read file ../mann/Dialog::ShowAt.n
man2html: unable to open or read file ../mann/Dialog::ShowOnWindow.n
man2html: unable to open or read file ../mann/Dialog::~Dialog.n